<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  <title>std.utf</title>
  <link href="./css/style.css" rel="stylesheet" type="text/css"/>
  <!-- <link href="./img/icon.png" rel="icon" type="image/png"/> -->
  <script type="text/javascript" src="./js/jquery.js"></script>
  <script type="text/javascript" src="./js/modules.js"></script>
  <script type="text/javascript" src="./js/quicksearch.js"></script>
  <script type="text/javascript" src="./js/navigation.js"></script>
  <!--<script type="text/javascript" src="./js/jquery.treeview.js"></script>-->
  <script type="text/javascript">
    var g_moduleFQN = "std.utf";
  </script>
  
</head>
<body>
<div id="content">
  <h1><a href="./htmlsrc/std.utf.html" class="symbol">std.utf</a></h1>
  
<div class="summary">Encode and decode UTF-8, UTF-16 and UTF-32 strings.</div>
For Win32 systems, the C wchar_t type is UTF-16 and corresponds to the D
 wchar type.
 For linux systems, the C wchar_t type is UTF-32 and corresponds to
 the D utf.dchar type. 
<p class="bl"/>
 UTF character support is restricted to (\u0000 &lt;= character &lt;= \U0010FFFF).
<p class="sec_header">See Also:</p><a href="http://en.wikipedia.org/wiki/Unicode">Wikipedia</a><br>
	<a href="http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8">http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8</a><br>
	<a href="http://anubis.dkuug.dk/JTC1/SC2/WG2/docs/n1335">http://anubis.dkuug.dk/JTC1/SC2/WG2/docs/n1335</a>
<dl>
<dt class="decl">class <a class="symbol _class" name="UtfError" href="./htmlsrc/std.utf.html#L49" kind="class" beg="49" end="58">UtfError</a> : Error; <span class="attrs">[<span class="stc">deprecated</span>]</span> <a title="Permalink to this symbol" href="#UtfError" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L49">#</a></dt>
<dd class="ddef">
<dl>
<dt class="decl">size_t <a class="symbol _variable" name="UtfError.idx" href="./htmlsrc/std.utf.html#L51" kind="variable" beg="51" end="51">idx</a>; <a title="Permalink to this symbol" href="#UtfError.idx" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L51">#</a></dt>
<dd class="ddef"></dd>
<dt class="decl"><a class="symbol _ctor" name="UtfError.this" href="./htmlsrc/std.utf.html#L53" kind="ctor" beg="53" end="57">this</a><span class="params">(char[] <em>s</em>, size_t <em>i</em>)</span>; <a title="Permalink to this symbol" href="#UtfError.this" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L53">#</a></dt>
<dd class="ddef"></dd></dl></dd>
<dt class="decl">class <a class="symbol _class" name="UtfException" href="./htmlsrc/std.utf.html#L64" kind="class" beg="64" end="73">UtfException</a> : Exception; <a title="Permalink to this symbol" href="#UtfException" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L64">#</a></dt>
<dd class="ddef">
<div class="summary">Exception class that is thrown upon any errors.</div>
<dl>
<dt class="decl">size_t <a class="symbol _variable" name="UtfException.idx" href="./htmlsrc/std.utf.html#L66" kind="variable" beg="66" end="66">idx</a>; <a title="Permalink to this symbol" href="#UtfException.idx" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L66">#</a></dt>
<dd class="ddef">
<div class="summary">index in string of where error occurred</div></dd>
<dt class="decl"><a class="symbol _ctor" name="UtfException.this" href="./htmlsrc/std.utf.html#L68" kind="ctor" beg="68" end="72">this</a><span class="params">(char[] <em>s</em>, size_t <em>i</em>)</span>; <a title="Permalink to this symbol" href="#UtfException.this" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L68">#</a></dt>
<dd class="ddef"></dd></dl></dd>
<dt class="decl">bool <a class="symbol _function" name="isValidDchar" href="./htmlsrc/std.utf.html#L85" kind="function" beg="85" end="95">isValidDchar</a><span class="params">(dchar <em>c</em>)</span>; <a title="Permalink to this symbol" href="#isValidDchar" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L85">#</a></dt>
<dd class="ddef">
<div class="summary">Test if c is a valid UTF-32 character.</div>
\uFFFE and \uFFFF are considered valid by this function,
 as they are permitted for internal use by an application,
 but they are not allowed for interchange by the Unicode standard.
<p class="sec_header">Returns:</p>true if it is, false if not.</dd>
<dt class="decl"><a class="symbol _unittest" name="unittest" href="./htmlsrc/std.utf.html#L97" kind="unittest" beg="97" end="102">unittest</a>; <a title="Permalink to this symbol" href="#unittest" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L97">#</a></dt>
<dd class="ddef"></dd>
<dt class="decl">ubyte[256] <a class="symbol _variable" name="UTF8stride" href="./htmlsrc/std.utf.html#L105" kind="variable" beg="105" end="123">UTF8stride</a>; <a title="Permalink to this symbol" href="#UTF8stride" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L105">#</a></dt>
<dd class="ddef"></dd>
<dt class="decl">uint <a class="symbol _function" name="stride" href="./htmlsrc/std.utf.html#L133" kind="function" beg="133" end="136">stride</a><span class="params">(char[] <em>s</em>, size_t <em>i</em>)</span>; <a title="Permalink to this symbol" href="#stride" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L133">#</a></dt>
<dd class="ddef">
<div class="summary">stride() returns the length of a UTF-8 sequence starting at index i
 in string s.</div>
<p class="sec_header">Returns:</p>The number of bytes in the UTF-8 sequence or
	0xFF meaning s[i] is not the start of of UTF-8 sequence.</dd>
<dt class="decl">uint <a class="symbol _function" name="stride:2" href="./htmlsrc/std.utf.html#L143" kind="function" beg="143" end="146">stride</a><span class="params">(wchar[] <em>s</em>, size_t <em>i</em>)</span>; <a title="Permalink to this symbol" href="#stride:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L143">#</a></dt>
<dd class="ddef">
<div class="summary">stride() returns the length of a UTF-16 sequence starting at index i
 in string s.</div></dd>
<dt class="decl">uint <a class="symbol _function" name="stride:3" href="./htmlsrc/std.utf.html#L154" kind="function" beg="154" end="157">stride</a><span class="params">(dchar[] <em>s</em>, size_t <em>i</em>)</span>; <a title="Permalink to this symbol" href="#stride:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L154">#</a></dt>
<dd class="ddef">
<div class="summary">stride() returns the length of a UTF-32 sequence starting at index i
 in string s.</div>
<p class="sec_header">Returns:</p>The return value will always be 1.</dd>
<dt class="decl">size_t <a class="symbol _function" name="toUCSindex" href="./htmlsrc/std.utf.html#L165" kind="function" beg="165" end="184">toUCSindex</a><span class="params">(char[] <em>s</em>, size_t <em>i</em>)</span>; <a title="Permalink to this symbol" href="#toUCSindex" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L165">#</a></dt>
<dt class="decl">size_t <a class="symbol _function" name="toUCSindex:2" href="./htmlsrc/std.utf.html#L188" kind="function" beg="188" end="205">toUCSindex</a><span class="params">(wchar[] <em>s</em>, size_t <em>i</em>)</span>; <a title="Permalink to this symbol" href="#toUCSindex:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L188">#</a></dt>
<dt class="decl">size_t <a class="symbol _function" name="toUCSindex:3" href="./htmlsrc/std.utf.html#L209" kind="function" beg="209" end="212">toUCSindex</a><span class="params">(dchar[] <em>s</em>, size_t <em>i</em>)</span>; <a title="Permalink to this symbol" href="#toUCSindex:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L209">#</a></dt>
<dd class="ddef">
<div class="summary">Given an index i into an array of characters s[],
 and assuming that index i is at the start of a UTF character,
 determine the number of UCS characters up to that index i.</div></dd>
<dt class="decl">size_t <a class="symbol _function" name="toUTFindex" href="./htmlsrc/std.utf.html#L218" kind="function" beg="218" end="230">toUTFindex</a><span class="params">(char[] <em>s</em>, size_t <em>n</em>)</span>; <a title="Permalink to this symbol" href="#toUTFindex" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L218">#</a></dt>
<dt class="decl">size_t <a class="symbol _function" name="toUTFindex:2" href="./htmlsrc/std.utf.html#L234" kind="function" beg="234" end="244">toUTFindex</a><span class="params">(wchar[] <em>s</em>, size_t <em>n</em>)</span>; <a title="Permalink to this symbol" href="#toUTFindex:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L234">#</a></dt>
<dt class="decl">size_t <a class="symbol _function" name="toUTFindex:3" href="./htmlsrc/std.utf.html#L248" kind="function" beg="248" end="251">toUTFindex</a><span class="params">(dchar[] <em>s</em>, size_t <em>n</em>)</span>; <a title="Permalink to this symbol" href="#toUTFindex:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L248">#</a></dt>
<dd class="ddef">
<div class="summary">Given a UCS index n into an array of characters s[], return the UTF index.</div></dd>
<dt class="decl">dchar <a class="symbol _function" name="decode" href="./htmlsrc/std.utf.html#L261" kind="function" beg="261" end="346">decode</a><span class="params">(char[] <em>s</em>, inout size_t <em>idx</em>)</span>; <a title="Permalink to this symbol" href="#decode" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L261">#</a></dt>
<dt class="decl">dchar <a class="symbol _function" name="decode:2" href="./htmlsrc/std.utf.html#L403" kind="function" beg="403" end="456">decode</a><span class="params">(wchar[] <em>s</em>, inout size_t <em>idx</em>)</span>; <a title="Permalink to this symbol" href="#decode:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L403">#</a></dt>
<dt class="decl">dchar <a class="symbol _function" name="decode:3" href="./htmlsrc/std.utf.html#L460" kind="function" beg="460" end="477">decode</a><span class="params">(dchar[] <em>s</em>, inout size_t <em>idx</em>)</span>; <a title="Permalink to this symbol" href="#decode:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L460">#</a></dt>
<dd class="ddef">
<div class="summary">Decodes and returns character starting at s[idx]. idx is advanced past the
 decoded character. If the character is not well formed, a UtfException is
 thrown and idx remains unchanged.</div></dd>
<dt class="decl"><a class="symbol _unittest" name="unittest:2" href="./htmlsrc/std.utf.html#L348" kind="unittest" beg="348" end="399">unittest</a>; <a title="Permalink to this symbol" href="#unittest:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L348">#</a></dt>
<dd class="ddef"></dd>
<dt class="decl">void <a class="symbol _function" name="encode" href="./htmlsrc/std.utf.html#L486" kind="function" beg="486" end="532">encode</a><span class="params">(inout char[] <em>s</em>, dchar <em>c</em>)</span>; <a title="Permalink to this symbol" href="#encode" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L486">#</a></dt>
<dt class="decl">void <a class="symbol _function" name="encode:2" href="./htmlsrc/std.utf.html#L555" kind="function" beg="555" end="577">encode</a><span class="params">(inout wchar[] <em>s</em>, dchar <em>c</em>)</span>; <a title="Permalink to this symbol" href="#encode:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L555">#</a></dt>
<dt class="decl">void <a class="symbol _function" name="encode:3" href="./htmlsrc/std.utf.html#L581" kind="function" beg="581" end="589">encode</a><span class="params">(inout dchar[] <em>s</em>, dchar <em>c</em>)</span>; <a title="Permalink to this symbol" href="#encode:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L581">#</a></dt>
<dd class="ddef">
<div class="summary">Encodes character c and appends it to array s[].</div></dd>
<dt class="decl"><a class="symbol _unittest" name="unittest:3" href="./htmlsrc/std.utf.html#L534" kind="unittest" beg="534" end="551">unittest</a>; <a title="Permalink to this symbol" href="#unittest:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L534">#</a></dt>
<dd class="ddef"></dd>
<dt class="decl">void <a class="symbol _function" name="validate" href="./htmlsrc/std.utf.html#L598" kind="function" beg="598" end="607">validate</a><span class="params">(char[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#validate" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L598">#</a></dt>
<dt class="decl">void <a class="symbol _function" name="validate:2" href="./htmlsrc/std.utf.html#L611" kind="function" beg="611" end="620">validate</a><span class="params">(wchar[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#validate:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L611">#</a></dt>
<dt class="decl">void <a class="symbol _function" name="validate:3" href="./htmlsrc/std.utf.html#L624" kind="function" beg="624" end="633">validate</a><span class="params">(dchar[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#validate:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L624">#</a></dt>
<dd class="ddef">
<div class="summary">Checks to see if string is well formed or not. Throws a UtfException if it is
 not. Use to check all untrusted input for correctness.</div></dd>
<dt class="decl">char[] <a class="symbol _function" name="toUTF8" href="./htmlsrc/std.utf.html#L637" kind="function" beg="637" end="671">toUTF8</a><span class="params">(char[4] <em>buf</em>, dchar <em>c</em>)</span>; <a title="Permalink to this symbol" href="#toUTF8" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L637">#</a></dt>
<dd class="ddef"></dd>
<dt class="decl">char[] <a class="symbol _function" name="toUTF8:2" href="./htmlsrc/std.utf.html#L677" kind="function" beg="677" end="685">toUTF8</a><span class="params">(char[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF8:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L677">#</a></dt>
<dt class="decl">char[] <a class="symbol _function" name="toUTF8:3" href="./htmlsrc/std.utf.html#L689" kind="function" beg="689" end="713">toUTF8</a><span class="params">(wchar[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF8:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L689">#</a></dt>
<dt class="decl">char[] <a class="symbol _function" name="toUTF8:4" href="./htmlsrc/std.utf.html#L717" kind="function" beg="717" end="741">toUTF8</a><span class="params">(dchar[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF8:4" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L717">#</a></dt>
<dd class="ddef">
<div class="summary">Encodes string s into UTF-8 and returns the encoded string.</div></dd>
<dt class="decl">wchar[] <a class="symbol _function" name="toUTF16" href="./htmlsrc/std.utf.html#L745" kind="function" beg="745" end="763">toUTF16</a><span class="params">(wchar[2] <em>buf</em>, dchar <em>c</em>)</span>; <a title="Permalink to this symbol" href="#toUTF16" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L745">#</a></dt>
<dd class="ddef"></dd>
<dt class="decl">wchar[] <a class="symbol _function" name="toUTF16:2" href="./htmlsrc/std.utf.html#L771" kind="function" beg="771" end="793">toUTF16</a><span class="params">(char[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF16:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L771">#</a></dt>
<dt class="decl">wchar* <a class="symbol _function" name="toUTF16z" href="./htmlsrc/std.utf.html#L797" kind="function" beg="797" end="820">toUTF16z</a><span class="params">(char[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF16z" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L797">#</a></dt>
<dt class="decl">wchar[] <a class="symbol _function" name="toUTF16:3" href="./htmlsrc/std.utf.html#L824" kind="function" beg="824" end="832">toUTF16</a><span class="params">(wchar[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF16:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L824">#</a></dt>
<dt class="decl">wchar[] <a class="symbol _function" name="toUTF16:4" href="./htmlsrc/std.utf.html#L836" kind="function" beg="836" end="848">toUTF16</a><span class="params">(dchar[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF16:4" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L836">#</a></dt>
<dd class="ddef">
<div class="summary">Encodes string s into UTF-16 and returns the encoded string.
 toUTF16z() is suitable for calling the 'W' functions in the Win32 API that take
 an LPWSTR or LPCWSTR argument.</div></dd>
<dt class="decl">dchar[] <a class="symbol _function" name="toUTF32" href="./htmlsrc/std.utf.html#L856" kind="function" beg="856" end="873">toUTF32</a><span class="params">(char[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF32" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L856">#</a></dt>
<dt class="decl">dchar[] <a class="symbol _function" name="toUTF32:2" href="./htmlsrc/std.utf.html#L877" kind="function" beg="877" end="894">toUTF32</a><span class="params">(wchar[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF32:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L877">#</a></dt>
<dt class="decl">dchar[] <a class="symbol _function" name="toUTF32:3" href="./htmlsrc/std.utf.html#L898" kind="function" beg="898" end="906">toUTF32</a><span class="params">(dchar[] <em>s</em>)</span>; <a title="Permalink to this symbol" href="#toUTF32:3" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L898">#</a></dt>
<dd class="ddef">
<div class="summary">Encodes string s into UTF-32 and returns the encoded string.</div></dd>
<dt class="decl"><a class="symbol _unittest" name="unittest:4" href="./htmlsrc/std.utf.html#L910" kind="unittest" beg="910" end="969">unittest</a>; <a title="Permalink to this symbol" href="#unittest:4" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/std.utf.html#L910">#</a></dt>
<dd class="ddef"></dd></dl>
</div>
<div id="footer">
  <p>Copyright © 1999-2008 by Digital Mars ®, All Rights Reserved.</p>
  <p>Page generated by <a href="http://code.google.com/p/dil">dil</a> on Fri Dec 26 03:40:14 2008. Rendered by <a href="http://code.google.com/p/dil/wiki/Kandil">kandil</a>.</p>
</div>
</body>
</html>